import { Meta, Status, Props, Story } from '../../../../../.storybook/components';
import * as Stories from './Tooltip.stories';

<Meta of={Stories} />

# Tooltip

<Status variant="deprecated">
  Use the [Tooltip](Components/Tooltip/Docs) or [Toggletip](Components/Toggletip/Docs) components instead.
</Status>

<Story of={Stories.Base} />

<Props />


## Dependencies

The Tooltip component depends on [Emotion.js](https://github.com/emotion-js/emotion) which isn't included in Circuit UI. Install it manually before using the components:

```bash
# npm
npm install @emotion/react@^11 @emotion/styled@^11
# yarn v1
yarn add @emotion/react@^11 @emotion/styled@^11
```

The Tooltip component depends on the legacy JSON theme. Wrap the the component or your entire application in the `ThemeProvider` from Emotion.js:

```tsx
import { ThemeProvider } from '@emotion/react';
import { light } from '@sumup-oss/design-tokens';
import { Tooltip } from '@sumup-oss/circuit-ui/legacy';

export default function App() {
  return (
    <ThemeProvider theme={light}>
      <Tooltip />
    </ThemeProvider>
  );
}
```

## Positions

<Story of={Stories.Positions} />

## Migration

Tooltips and Toggletips hide information by default and require user interaction to be shown. They should be used as a last resort when space truly is limited. Often, it is preferable to use the [Input](Components/Input/Docs)'s `validationHint` or the [Checkbox](Components/Checkbox/Docs), [RadioButton](Components/RadioButton/Docs) or [Toggle](Components/Toggle/Docs)'s `explanation` prop instead to display the information inline.

While the deprecated Tooltip component only focused on the look and position of its content, the new Tooltip and Toggletip components also take the semantic context and relationship to their reference element into account.

### Tooltip

Use the new [Tooltip](Components/Tooltip/Docs) component when it acts as the reference element's [main label](https://w3c.github.io/accname/#dfn-accessible-name) or [supplemental description](https://w3c.github.io/accname/#dfn-accessible-description) and appears on _hover_ or _focus_ of the reference element.

Here's an example:

```tsx
// Before
import { useState } from "react";
import { Badge } from "@sumup-oss/circuit-ui";
import { Tooltip } from "@sumup-oss/circuit-ui/legacy";

function Component() {
  const [isVisible, setVisible] = useState(false);
  return (
    <div>
      {isVisible && (
        <Tooltip position="top" align="right">
          A chargeback is a return of money to a payer of a transaction,
          especially a credit card transaction.
        </Tooltip>
      )}
      {/* This implementation wasn't accessible to keyboard users */}
      <Badge
        onMouseEnter={() => setVisible(true)}
        onMouseLeave={() => setVisible(false)}
      >
        Chargeback
      </Badge>
    </div>
  );
}
```

```tsx
// After
import { Badge, Tooltip } from "@sumup-oss/circuit-ui";

function Component() {
  return (
    <Tooltip
      type="description"
      label="A chargeback is a return of money to a payer of a transaction, especially a credit card transaction."
      component={(props) => (
        // The reference element must be focusable
        <Badge {...props} tabIndex="0">
          Chargeback
        </Badge>
      )}
    />
  );
}
```

### Toggletip

Use the new [Toggletip](Components/Toggletip/Docs) component if the content should be structured or interactive and the reference element's sole purpose is toggling the tip.

Here's an example:

```tsx
// Before
import { useState } from "react";
import { Tooltip } from "@sumup-oss/circuit-ui/legacy";
import { Info } from "@sumup-oss/icons";

function Component() {
  const [isVisible, setVisible] = useState(false);
  return (
    <div>
      {isVisible && (
        <Tooltip position="top" align="right">
          <h2>What is a chargeback?</h2>
          <p>
            A chargeback is a return of money to a payer of a transaction,
            especially a credit card transaction.
          </p>
        </Tooltip>
      )}
      {/* This implementation wasn't accessible because screenreader and
          keyboard users couldn't perceive the interactive element. */}
      <Info onClick={() => setVisible((prev) => !prev)} size="16" />
    </div>
  );
}
```

```tsx
// After
import { IconButton, Toggletip } from "@sumup-oss/circuit-ui";
import { Info } from "@sumup-oss/icons";

function Component() {
  return (
    <Toggletip
      headline="What is a chargeback?"
      body="A chargeback is a return of money to a payer of a transaction, especially a credit card transaction."
      component={(props) => (
        // The reference element must be a button
        <IconButton {...props} icon={Info}>
          Show details
        </IconButton>
      )}
    />
  );
}
```
